/*
 * This file is part of the Sx Framework Library.
 * 
 * Copyright (C) 2013 University of Colorado Denver
 * <min.choi@ucdenver.edu> <shane.transue@ucdenver.edu>
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy 
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
 * copies of the Software, and to permit persons to whom the Software is 
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in 
 * all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
 * DEALINGS IN THE SOFTWARE.
 */
#ifndef SX_LINE_PARSER_H
#define SX_LINE_PARSER_H

#include <sxString.h>

namespace Sx {
namespace File {

/*
 * Provides a default buffer length for the length of a line in an Ascii
 * text file: 2^12
 */
const static unsigned int TEXT_FILE_LINE_BUFFER_LENGTH = 4096;

/*
 * Opaque pointer type for the LineParser class.
 */
namespace Detail {
struct LineParserImp;
}

/*
 * The LineParser class provides a basic utility for quickly parsing the lines
 * of a ASCII text file. This provides a clean interface for parsing a text
 * file line by line. Example usage:
 *
 * while ( lineParser.hasNext() ) line = lineParser.nextLine();
 *
 * Note that it is critical to include the nextLine() function inside the
 * while loop. This is because the end of the file is only detected by the 
 * nextLine() function; therefore if it is not used the hasNext() function
 * will always return true.
 */
class LineParser {
public:
	LineParser(unsigned int bufferLength = TEXT_FILE_LINE_BUFFER_LENGTH);
	~LineParser();

	/*
	 * Opens the provided filename.
	 */
	bool open(const String& filename);

	/*
	 * Determines if the open file still has lines to be parsed. If the file
	 * contains more lines to be parsed then this function will return true;
	 * otherwise the end of the file has been reached and this function will
	 * return false. Additionally, if this LineParser does not have an open
	 * file this function will return false.
	 */
	bool hasNext();

	/*
	 * Returns the next line from the current position in the open text file.
	 * If this LineParser does not have an open file then the function will
	 * return an empty String.
	 */
	String nextLine();

	/*
	 * Closes the open file.
	 */
	void close();

private:
	/*
	 * An opaque pointer is used to hide the implementation details of this
	 * class so that the implementation can easily be changed.
	 */
	Detail::LineParserImp* imp;
};

}

}

#endif
